home *** CD-ROM | disk | FTP | other *** search
/ Programmer Power Tools / Programmer Power Tools.iso / math / math.arc / FABS.DOC < prev    next >
Text File  |  1988-07-21  |  11KB  |  390 lines
  1.  
  2. November 11, 1983  ( Initial )
  3. November 25, 1983  ( Added REPLACE and DELETE )
  4.  
  5. FABS is an assembly language program module designed for use with the
  6.    IBM PC to maintain key files for fast retrieval of data using
  7.    random records.
  8.  
  9. FABS is supplied by Computer Control Systems, Inc.
  10.                     298 21st Terrace S.E.
  11.                     Largo, Fl 33541
  12.  
  13. FABS comes with an interface to BASIC ( Compiled and Interpreted )
  14.    and PASCAL. This documentation is for an interface to FABS that I
  15.    have written. I have also written an interface in FORTH.
  16.  
  17. QUESTIONS, SUGGESTIONS and COMPLAINTS can be sent to me :
  18.    Norman McIntosh
  19.    771 Dolores
  20.    San Francisco, Ca. 94110
  21.    415-648-2476
  22.  
  23.  
  24.               F A B S      D O C U M E N T A T I O N
  25.               ======================================
  26.  
  27. NAME
  28.    fabs_create -- create a FABS index file
  29.  
  30. SYNOPSIS
  31.    fabs_create( file_name, key_len, num_keys, key_type, file_num )
  32.    char *file_name ;         FABS file name
  33.    int key_len ;             max number of bytes in a FABS key
  34.    int num_keys ;            number of FABS keys
  35.    char key_type ;           FABS file type 'A' or 'I'
  36.    int file_num ;            FABS file number
  37.  
  38. DESCRIPTION
  39.    Creates the FABS index file with the name as supplied by
  40.    *file_name and *file_name.MAP. Deletes files if present.
  41.  
  42. CAUTIONS
  43.    Aborts program if any errors occured.
  44.  
  45. ---------------------------------------------------------------------
  46.  
  47. NAME
  48.    fabs_open -- open a FABS file
  49.  
  50. SYNOPSIS
  51.    fabs_open( file_name, file_num )
  52.    char *file_name ;         FABS file name
  53.    int file_num ;            FABS file number
  54.  
  55. DESCRIPTION
  56.    Opens FABS file as specified by *file_name.
  57.  
  58. CAUTIONS
  59.    Aborts program if any errors occured.
  60.  
  61. ---------------------------------------------------------------------
  62.  
  63. NAME
  64.    fabs_first -- find first key in FABS file
  65.  
  66. SYNOPSIS
  67.    result = fabs_first( file_num, key_num )
  68.    int result ;              the warning code returned
  69.    int file_num ;            FABS file number
  70.    int key_num ;             the key number
  71.  
  72. DESCRIPTION
  73.    Finds the first logical record in the FABS file based on key
  74.    key_num.
  75.  
  76. RETURNS
  77.    result = error code
  78.    rec_fabs = record number in data file
  79.    key_fabs = The memory address (in FABS segment) of the key
  80.  
  81. CAUTIONS
  82.    Aborts program if any fatal errors occured.
  83.  
  84. ---------------------------------------------------------------------
  85.  
  86. NAME
  87.    fabs_last -- find last key in FABS file
  88.  
  89. SYNOPSIS
  90.    result = fabs_last( file_num, key_num )
  91.    int result ;              the warning code returned
  92.    int file_num ;            FABS file number
  93.    int key_num ;             the key number
  94.  
  95. DESCRIPTION
  96.    Finds the last logical record in the FABS file based on key
  97.    key_num.
  98.  
  99. RETURNS
  100.    result = error code
  101.    rec_fabs = record number in data file
  102.    key_fabs = The memory address (in FABS segment) of the key
  103.  
  104. CAUTIONS
  105.    Aborts program if any fatal errors occured.
  106.  
  107. ---------------------------------------------------------------------
  108.  
  109. NAME
  110.    fabs_next -- find next record in FABS file
  111.  
  112. SYNOPSIS
  113.    result = fabs_next( file_num )
  114.    int result ;              the warning code returned
  115.    int file_num ;            FABS file number
  116.  
  117. DESCRIPTION
  118.    Finds the next logical record in the FABS file.
  119.  
  120. RETURNS
  121.    result = error code
  122.    rec_fabs = record number in data file
  123.    key_fabs = The memory address (in FABS segment) of the key
  124.  
  125. CAUTIONS
  126.    Aborts program if any fatal errors occured. Next will not cross
  127.    over primary key boundaries, that is, when SEARCHING NEXT for
  128.    a given primary key, an error #15 will will occur after reaching
  129.    the end of the group of primary keys.
  130.  
  131. ---------------------------------------------------------------------
  132.  
  133. NAME
  134.    fabs_previous -- find previous record
  135.  
  136. SYNOPSIS
  137.    result = fabs_previous( file_num )
  138.    int result ;   -------
  139.  
  140. NAME
  141.    fabs_previous -- find previous record
  142.  
  143. SYNOPSIS
  144.    result = fabs_previous( file_num )
  145.    int result ;              the warning code returned
  146.    int file_num ;            FABS file number
  147.  
  148. DESCRIPTION
  149.    Finds the previous logical record in the FABS file.
  150.  
  151. RETURNS
  152.    result = error code
  153.    rec_fabs = record number in data file
  154.    key_fabs = The memory address (in FABS segment) of the key
  155.  
  156. CAUTIONS
  157.    Aborts program if any fatal errors occured. Previous will not cross
  158.    over primary key boundaries, that is, when SEARCHING PREVIOUS for
  159.    a given primary key, an error #13 will will occur after reaching
  160.    the bottom of the group of primary keys.
  161.  
  162. ---------------------------------------------------------------------
  163.  
  164. NAME
  165.    fabs_generic -- search FABS file for first record => key
  166.  
  167. SYNOPSIS
  168.    result = fabs_generic( key_num, file_num, key )
  169.    int result ;              the warning code returned
  170.    int key_num ;             the key number
  171.    int file_num ;            FABS file number
  172.    char *key ;               FABS key to find
  173.  
  174. DESCRIPTION
  175.    Finds the first occurrence of the left justified partial key.
  176.  
  177. RETURNS
  178.    result = error code
  179.    rec_fabs = record number in data file
  180.    key_fabs = The memory address (in FABS segment) of the key
  181.  
  182. CAUTIONS
  183.    Aborts program if any fatal errors occured. Previous will not cross
  184.    over primary key boundaries, that is, when SEARCHING PREVIOUS for
  185.    a given primary key, an error #13 will will occur after reaching
  186.    the bottom of the group of primary keys.
  187.  
  188. ---------------------------------------------------------------------
  189.  
  190. NAME
  191.    fabs_search -- search FABS file for record = key
  192.  
  193. SYNOPSIS
  194.    result = fabs_search( key_num, file_num, key )
  195.    int result ;              the warning code returned
  196.    int key_num ;             the key number
  197.    int file_num ;            FABS file number
  198.    char *key ;               FABS key to find
  199.  
  200. DESCRIPTION
  201.    Finds the record number of the key contained in *key.
  202.  
  203. RETURNS
  204.    result = error code
  205.    rec_fabs = record number in data file
  206.    key_fabs = The memory address (in FABS segment) of the key
  207.  
  208. CAUTIONS
  209.    Aborts program if any fatal errors occured.
  210.  
  211. ---------------------------------------------------------------------
  212.  
  213. NAME
  214.    fabs_insert -- insert key into FABS file
  215.  
  216. SYNOPSIS
  217.    fabs_insert( keys, file_num )
  218.    char *keys ;              FABS keys to insert
  219.    int file_num ;            FABS file number
  220.  
  221. DESCRIPTION
  222.    Insert key contained in *key into the FABS file.
  223.  
  224. RETURNS
  225.    rec_fabs = record number in data file
  226.  
  227. CAUTIONS
  228.    Aborts program if any errors occured.
  229.  
  230. ---------------------------------------------------------------------
  231.  
  232. NAME
  233.    fabs_delete -- delete key from FABS file
  234.  
  235. SYNOPSIS
  236.    fabs_delete( rec_num, SBDF, file_num, keys )
  237.    int rec_num ;             File record number to delete
  238.    char SBDF ;               Search before delete if 'Y'
  239.    int file_num ;            FABS file number
  240.    char *keys ;              FABS keys to delete
  241.  
  242. DESCRIPTION
  243.    Delete key contained in *key from the FABS file. If SBDF is 'N'
  244.    the keys are not searched to ensure they are correct before
  245.    deletion takes place.
  246.  
  247. RETURNS
  248.    rec_fabs = record number in that was deleted ( same as rec_num )
  249.  
  250. CAUTIONS
  251.    Aborts program if any errors occured.
  252.  
  253. ---------------------------------------------------------------------
  254.  
  255. NAME
  256.    fabs_replace -- replace key in FABS file
  257.  
  258. SYNOPSIS
  259.    fabs_replace( key_num, rec_num, file_num, old_key, new_key )
  260.    int key_num ;             Primary key number to replace
  261.    int rec_num ;             File record number to replace
  262.    int file_num ;            FABS file number
  263.    char *old_key ;           FABS old key to replace
  264.    char *new_key ;           FABS new key to replace
  265.  
  266. DESCRIPTION
  267.    Replace the key contained in *old_key by the key contained in
  268.    *new_key.
  269.  
  270. RETURNS
  271.    rec_fabs = record number in that was replaced ( same as rec_num )
  272.  
  273. CAUTIONS
  274.    Aborts program if any errors occured.
  275.  
  276. ---------------------------------------------------------------------
  277.  
  278. NAME
  279.    fabs_build -- insert key into FABS file, without update to map file
  280.  
  281. SYNOPSIS
  282.    fabs_build( keys, file_num )
  283.    char *keys ;              FABS keys to insert
  284.    int file_num ;            FABS file number
  285.  
  286. DESCRIPTION
  287.    Insert key contained in *key into the FABS file, but does not write
  288.    the map file to disk.
  289.  
  290. RETURNS
  291.    rec_fabs = record number in data file
  292.  
  293. CAUTIONS
  294.    Aborts program if any errors occured. A fabs_write must be executed
  295.    after a series of builds to update the map file.
  296.  
  297. ---------------------------------------------------------------------
  298.  
  299. NAME
  300.    fabs_write -- write map file after series of builds
  301.  
  302. SYNOPSIS
  303.    fabs_write( file_num )
  304.    int file_num ;            FABS file number
  305.  
  306. DESCRIPTION
  307.    Write the map file to disk after a series of fabs_build.
  308.  
  309. CAUTIONS
  310.    Aborts program if any errors occured.
  311.  
  312. ---------------------------------------------------------------------
  313.  
  314. NAME
  315.    fabs_close -- close FABS file
  316.  
  317. SYNOPSIS
  318.    fabs_write( file_num )
  319.    int file_num ;            FABS file number
  320.  
  321. DESCRIPTION
  322.    Close the FABS file. This function is only needed before the
  323.    calling program exits.
  324.  
  325. CAUTIONS
  326.    Aborts program if any errors occured.
  327.  
  328. ---------------------------------------------------------------------
  329.  
  330. NAME
  331.    fabs_key_length -- get the maximum length of the FABS key
  332.  
  333. SYNOPSIS
  334.    fabs_key_length( file_num )
  335.    int file_num ;            FABS file number
  336.  
  337. DESCRIPTION
  338.    Gets the maximum length of the FABS key.
  339.  
  340. RETURNS
  341.    rec_fabs = the maximum length of the key file
  342.  
  343. CAUTIONS
  344.    Aborts program if any errors occured.
  345.  
  346. ---------------------------------------------------------------------
  347.  
  348. NAME
  349.    fabs_get_key -- get FABS key from index area
  350.  
  351. SYNOPSIS
  352.    fabs_get_key( file_num, key )
  353.    int file_num ;            FABS file number
  354.    char *key ;               FABS current key
  355.  
  356. DESCRIPTION
  357.    Gets the current key in the FABS file.
  358.  
  359. RETURNS
  360.    key = the key of the current record in the FABS file
  361.  
  362. CAUTIONS
  363.    Aborts program if any errors occured.
  364.  
  365. ---------------------------------------------------------------------
  366.  
  367.                F A B S   E R R O R S   /   W A R N I N G S
  368.                ===========================================
  369.  
  370. ERROR#  WARN   DESCRIPTION
  371. ------  ----   ------------------------------------------------------
  372.    4           Imporper key for integer key file
  373.    5           Attempted generic search on integer key
  374.    6           Key not found on delete
  375.    7           Incorrect number of primary keys
  376.    8           Syntax error in command string
  377.    9           No more key space
  378.   10           Input key larger than maximum
  379.   11           Tried to access unopened file
  380.   12     **    Key not found, but keys both larger and smaller
  381.   13     **    Key not found, key smaller than all keys
  382.   15     **    Key not found, key larger than all keys
  383.   16     **    Key not found, no keys in key file
  384.   22           Key file not present when opened
  385.   23           Out of directory space
  386.   24           Diskette full
  387.   25           Write error
  388.   26           File not present when closed
  389.   27           Read error, end of file
  390.